Amiga Plus 2000 #4

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Plus 2000 #4 / Amiga Plus CD - 2000 - No. 4.iso / Tools / Commo-Support / Disk-Archive / includes-1_4.dms / includes-1_4.adf / doc.zoo / dos.doc < prev next >

Wrap

Text File | 1989-12-19 | 100.7 KB | 3,973 lines

TABLE OF CONTENTS 10-10-88 dos.library/Close dos.library/CreateDir dos.library/CreateProc dos.library/CurrentDir dos.library/DateStamp dos.library/Delay dos.library/DeleteFile dos.library/DeviceProc dos.library/DupLock dos.library/Examine dos.library/Execute dos.library/Exit dos.library/ExNext dos.library/Info dos.library/Input dos.library/IoErr dos.library/IsInteractive dos.library/LoadSeg dos.library/Lock dos.library/Open dos.library/Output dos.library/ParentDir dos.library/Read dos.library/Rename dos.library/Seek dos.library/SetComment dos.library/SetProtection dos.library/UnLoadSeg dos.library/UnLock dos.library/WaitForChar dos.library/Write dos.library/Close NAME Close -- Close an open file SYNOPSIS Close( file ) D1 struct FileHandle *file; FUNCTION The file specified by the file handle is closed. You must close all files you explicitly opened, but you must not close inherited file handles that are passed to you (each filehandle must be closed once and ONLY once). INPUTS file - BCPL pointer to a file handle SEE ALSO Open dos.library/CreateDir NAME CreateDir -- Create a new directory SYNOPSIS lock = CreateDir( name ) D0 D1 struct FileLock *lock; char *name; FUNCTION CreateDir creates a new directory with the specified name. An error is returned if it fails. Directories can only be created on devices which support them, e.g. disks. A return of zero means that AmigaDOS has found an error you should then call IoErr() to find out more; otherwise, CreateDir returns an exclusive lock on the new directory. INPUTS name - pointer to a null-terminated string OUTPUTS lock - BCPL pointer to a lock dos.library/CreateProc NAME CreateProc -- Create a new process SYNOPSIS process = CreateProc( name, pri, segment, stackSize ) D0 D1 D2 D3 D4 struct Process *process; char *name; LONG pri, stackSize; BPTR *segment; FUNCTION CreateProc cretes a new AmigaDOS process of name 'name'. AmigaDOS processes are a superset of exec tasks. A segment list, as returned by LoadSeg(), is passed as 'seglist'. This represents a section of code which is to be run as a new process. The code is entered at the first hunk in the segment list, which should contain suitable initialization code or a jump to such. A process control structure is allocated from memory and initialized. If you wish to fake a segment list (that will never have DOS UnLoadSeg() called on it), use this code: ds.l 0 ;Align to longword DC.L 16 ;Segment "length" (faked) DC.L 0 ;Pointer to next segment ...start of code... The size of the root stack upon activation is passed as 'stackSize'. 'pri' specifies the required priority of the new process. The result will be the process identifier of the new process, or zero if the routine failed. The argument 'name' specifies the new process name. A zero return code indicates error. INPUTS name - pointer to a null-terminated string pri - signed integer segment - BCPL pointer to a segment stackSize - integer (must be a multiple of 4 bytes) OUTPUTS process - process identifier dos.library/CurrentDir NAME CurrentDir -- Make a directory associated with a lock the working directory SYNOPSIS oldLock = CurrentDir( lock ) D0 D1 struct FileLock *oldlock, *lock; FUNCTION CurrentDir() causes a directory associated with a lock to be made the current directory. The old current directory lock is returned. A value of zero is a valid result here, this 0 lock represents the root of file system that you booted from (which is, in effect, the parent of all other file system roots.) INPUTS lock - BCPL pointer to a lock OUTPUTS oldLock - BCPL pointer to a lock SEE ALSO Lock dos.library/DateStamp NAME DateStamp -- Obtain the date and time in internal format SYNOPSIS DateStamp( v ); D1 LONG *v; FUNCTION DateStamp() takes a vector of three longwords that is set to the current time. The first element in the vector is a count of the number of days. The second element is the number of minutes elapsed in the day. The third is the number of ticks elapsed in the current minute. A tick happens 50 times a second. DateStamp ensures that the day and minute are consistent. All three elements are zero if the date is unset. DateStamp() currently only returns even multiples of 50 ticks. Therefore the time you get is always an even number of ticks. INPUTS v - pointer to an array of three longwords OUTPUTS The array is filled as described. dos.library/Delay NAME Delay -- Delay a process for a specified time SYNOPSIS Delay( ticks ) D1 LONG ticks; FUNCTION The argument 'ticks' specifies how many ticks (50 per second) to wait before returning control. BUGS Due to a bug in the timer.device in V1.2/V1.3, specifying a timeout of zero for Delay() can cause the unreliable timer & floppy disk operation. INPUTS ticks - integer dos.library/DeleteFile NAME DeleteFile -- Delete a file or directory SYNOPSIS success = DeleteFile( name ) D0 D1 BOOL success; char *name; FUNCTION This attempts to delete the file or directory specified by 'name'. An error is returned if the deletion fails. Note that all the files within a directory must be deleted before the directory itself can be deleted. INPUTS name - pointer to a null-terminated string OUTPUTS success - boolean SEE ALSO IoErr dos.library/DeviceProc NAME DeviceProc -- Return the process I.D. of specific I/O handler SYNOPSIS process = DeviceProc( name ) D0 D1 FUNCTION DeviceProc() returns the process identifier of the process which handles the device associated with the specified name. If no process handler can be found then the result is zero. If the name refers to a file on a mounted device then a pointer to a directory lock is returned in IoErr(). dos.library/DupLock NAME DupLock -- Duplicate a lock SYNOPSIS lock = DupLock( lock ) D0 D1 struct FileLock *newlock, *lock; FUNCTION DupLock() is passed a shared filing system lock. This is the ONLY way to obtain a duplicate of a lock... simply copying is not allowed. Another lock to the same object is then returned. It is not possible to create a copy of a write lock. A zero return indicates failure. INPUTS lock - BCPL pointer to a lock OUTPUTS newLock - BCPL pointer to a lock SEE ALSO Lock() dos.library/Examine NAME Examine -- Examine a directory or file associated with a lock SYNOPSIS success = Examine( lock, infoBlock ) D0 D1 D2 BOOL success; struct FileLock *lock; struct FileInfoBlock *infoBlock FUNCTION Examine() fills in information in the FileInfoBlock concerning the file or directory associated with the lock. This information includes the name, size, creation date and whether it is a file or directory. FileInfoBlock must be longword aligned. Examine() gives a return code of zero if it fails. You may make a local copy of the FileInfoBlock, as long as it is never passed back to the operating system. INPUTS lock - BCPL pointer to a lock infoBlock - pointer to a FileInfoBlock (must be longword aligned) OUTPUTS success - boolean dos.library/Execute NAME Execute -- Execute a CLI command SYNOPSIS success = Execute( commandString, input, output ) D0 D1 D2 D3 BOOL success char *commandString; struct FileHandle *input, *output; FUNCTION This function attempts to execute the string commandString as though it were a CLI command and arguments. The string can contain any valid input that you could type directly in a CLI, including input and output redirection using < and >. The input file handle will normally be zero, and in this case Execute() will perform whatever was requested in the commandString and then return. If the input file handle is nonzero then after the (possibly null) commandString is performed subsequent input is read from the specified input file handle until end of that file is reached. In most cases the output file handle must be provided, and is used by the CLI commands as their output stream unless output redirection was specified. If the output file handle is set to zero then the current window, normally specified as *, is used. Note that programs running under the Workbench do not normally have a current window. Execute() may also be used to create a new interactive CLI process just like those created with the NEWCLI function. In order to do this you would call Execute() with an empty commandString, and pass a file handle relating to a new window as the input file handle. The output file handle would be set to zero. The CLI will read commands from the new window, and will use the same window for output. This new CLI window can only be terminated by using the ENDCLI command. For this command to work the program RUN must be present in C:. INPUTS commandString - pointer to a null-terminated string input - BCPL pointer to a file handle output - BCPL pointer to a file handle OUTPUTS success - BOOLEAN indicating whether Execute was successful in finding and starting the specified program dos.library/Exit NAME Exit -- Exit from a program SYNOPSIS Exit( returnCode ) D1 LONG returnCode; FUNCTION Exit() is currently for use with programs written as if they were BCPL programs. This function is not normally useful for other purposes. In general, therefore, please DO NOT CALL THIS FUNCTION! In order to exit, C programs should use the C language exit() function (note the lower case letter "e"). Assembly programs should place a return code in D0, and execute an RTS instruction. IMPLEMENTATION The action of Exit() depends on whether the program which called it is running as a command under a CLI or not. If the program is running under the CLI the command finishes and control reverts to the CLI. In this case, returnCode is interpreted as the return code from the program. If the program is running as a distinct process, Exit() deletes the process and release the space associated with the stack, segment list and process structure. INPUTS returnCode - integer dos.library/ExNext NAME ExNext -- Examine the next entry in a directory SYNOPSIS success = ExNext( lock, infoBlock ) D0 D1 D2 BOOL success; struct FileLock *lock; struct FileInfoBlock *infoBlock; FUNCTION This routine is passed a directory lock and a FileInfoBlock that have been initialized by a previous call to Examine(), or updated by a previous call to ExNext. ExNext gives a return code of zero on failure. The most common cause of failure is reaching the end of the list of files in the owning directory. In this case, IoErr will return ERROR_NO_MORE_ENTRIES and a good exit is appropriate. So, follow these steps to examine a directory: 1) Pass a Lock and a FileInfoBlock to Examine(). The Lock must be on the directory you wish to examine. 2) Pass ExNext the same Lock and FileInfoBlock. 3) Do something with the information returned in the FileInfoBlock. Note that the type field is positive for directories, negative for files. 4) Keep calling ExNext until it returns FALSE. Check IoErr() to ensure that the reason for failure was ERROR_NO_MORE_ENTRIES. Note: if you wish to recursively scan the file tree and you find another directory while ExNext'ing you must Lock that directory and Examine() it using a new FileInfoBlock. Use of the same FileInfoBlock to enter a directory would lose important state information such that it will be impossible to continue scanning the parent directory. While it is permissible to UnLock and Lock the parent directory between ExNext calls, this is not recommended. Important state information is associated with the parent lock so if it is freed between ExNext calls this information has to be rebuilt on each new ExNext call and will significantly slow down directory scanning. It is NOT legal to Examine() a file, and then to ExNext from that FileInfoBlock. You may make a local copy of the FileInfoBlock, as long as it is never passed back to the operating system. INPUTS lock - BCPL pointer to a lock originally used for the Examine() call infoBlock - pointer to a FileInfoBlock used on the previous Examine() or ExNext() call. OUTPUTS success - boolean SPECIAL NOTE The FileInfoBlock must be longword aligned. dos.library/Info NAME Info -- Returns information about the disk SYNOPSIS success = Info( lock, parameterBlock ) D0 D1 D2 struct FileLock *lock; struct InfoData *parameterBlock FUNCTION Info() can be used to find information about any disk in use. 'lock' refers to the disk, or any file on the disk. The parameter block is returned with information about the size of the disk, number of free blocks and any soft errors. INPUTS lock - BCPL pointer to a lock parameterBlock - pointer to an InfoData structure (longword aligned) OUTPUTS success - boolean SPECIAL NOTE: Note that InfoData structure must be longword aligned. dos.library/IoErr NAME IoErr -- Return extra information from the system SYNOPSIS error = IoErr() D0 LONG error; FUNCTION I/O routines return zero to indicate an error. When this happens, this routine may be called to determine more information. It is also used in some routines to pass back a secondary result. OUTPUTS error - integer SEE ALSO Open, Read, ExNext dos.library/Input NAME Input -- Identify the program's initial input file handle SYNOPSIS file = Input() D0 struct FileHandle *file; FUNCTION Input() is used to identify the initial input stream allocated when the program was initiated. OUTPUTS file - BCPL pointer to a file handle SEE ALSO Output() dos.library/IsInteractive NAME IsInteractive -- Discover whether a file is a virtual terminal SYNOPSIS status = IsInteractive( file ) D0 D1 BOOL status; struct FileHandle *file; FUNCTION The return value 'status' indicates whether the file associated with the file handle 'file' is connected to a virtual terminal. INPUTS file - BCPL pointer to a file handle OUTPUTS status - boolean dos.library/LoadSeg NAME LoadSeg -- Load a load module into memory SYNOPSIS segment = LoadSeg( name ) D0 D1 BPTR segment; char *name; FUNCTION The file 'fileName' should be a load module produced by the linker. LoadSeg scatter loads the CODE, DATA and BSS segments into memory, chaining together the segments with BPTR's on their first words. The end of the chain is indicated by a zero. In the event of an error any blocks loaded will be unloaded and a FALSE (zero) result returned. If the module is correctly loaded then the output will be a pointer at the beginning of the list of blocks. Loaded code is unloaded via a call to UnLoadSeg(). INPUTS name - pointer to a null-terminated string OUTPUTS segment - BCPL pointer to a segment dos.library/Lock NAME Lock -- Lock a directory or file SYNOPSIS lock = Lock( name, accessMode ) D0 D1 D2 struct FileLock *lock; char *name; LONG accessMode; FUNCTION A filing system lock on the file or directory 'name' is returned if possible. If the accessMode is ACCESS_READ, the lock is a shared read lock; if the accessMode is ACCESS_WRITE then it is an exclusive write lock. If Lock() fails (that is, if it cannot obtain a filing system lock on the file or directory) it returns a zero. Note that the overhead for doing a Lock() is less than that for doing an Open(), so that, if you want to test to see if a file exists, you should use Lock(). Of course, once you've found that it exists, you must use Open() if you want to open it. Tricky assumptions about the internal format of a lock are unwise. INPUTS name - pointer to a null-terminated string accessMode - integer OUTPUTS lock - BCPL pointer to a lock dos.library/Open NAME Open -- Open a file for input or output SYNOPSIS file = Open( name, accessMode ) D0 D1 D2 struct FileHandle *file; char *name; LONG accessMode; FUNCTION The named file is opened and a file handle returned. If the accessMode is MODE_OLDFILE, an existing file is opened for reading or writing. If the value is MODE_NEWFILE, a new file is created for writing. MODE_READWRITE opens an old file with and exclusive lock. Open types are documented in the "libraries/dos.h" include file. The 'name' can be a filename (optionally prefaced by a device name), a simple device such as NIL:, a window specification such as CON: or RAW: followed by window parameters, or *, representing the current window. If the file cannot be opened for any reason, the value returned will be zero, and a secondary error code will be available by calling the routine IoErr(). INPUTS name - pointer to a null-terminated string accessMode - integer OUTPUTS file - BCPL pointer to a file handle dos.library/Output NAME Output -- Identify the programs' initial output file handle SYNOPSIS file = Output() D0 struct FileHandle *file; FUNCTION Output() is used to identify the initial output stream allocated when the program was initiated. OUTPUTS file - BCPL pointer to a file handle dos.library/ParentDir NAME ParentDir -- Obtain the parent of a directory or file SYNOPSIS newlock = ParentDir( lock ) D0 D1 struct FileLock *newlock, *lock; FUNCTION The argument 'lock' is associated with a given file or directory. ParentDir() returns 'newlock' which is associated the parent directory of 'lock'. Taking the ParentDir() of the root of the current filing system returns a NULL (0) lock. Note this 0 lock represents the root of file system that you booted from (which is, in effect, the parent of all other file system roots.) INPUTS lock - BCPL pointer to a lock OUTPUTS newlock - BCPL pointer to a lock dos.library/Read NAME Read -- Read bytes of data from a file SYNOPSIS actualLength = Read( file, buffer, length ) D0 D1 D2 D3 LONG actualLength; struct FileHandle *file; char *buffer; LONG length; FUNCTION Data can be copied using a combination of Read() and Write(). Read() reads bytes of information from an opened file (represented here by the argument 'file') into the buffer given. The argument 'length' is the length of the buffer given. The value returned is the length of the information actually read. So, when 'actualLength' is greater than zero, the value of 'actualLength' is the the number of characters read. Usually Read will try to fill up your buffer before returning. A value of zero means that end-of-file has been reached. Errors are indicated by a value of -1. In any case, the value of IoErr() is also modified by this call. If there was an error it gives more error information, otherwise it indicates whether there is any more data in the file. INPUTS file - BCPL pointer to a file handle buffer - pointer to buffer length - integer OUTPUTS actualLength - integer dos.library/Rename NAME Rename -- Rename a directory or file SYNOPSIS success = Rename( oldName, newName ) D0 D1 D2 BOOL success; char *oldName, *newName; FUNCTION Rename() attempts to rename the file or directory specified as 'oldName' with the name 'newName'. If the file or directory 'newName' exists, Rename() fails and returns an error. Both 'oldName' and the 'newName' can contain a directory specification. In this case, the file will be moved from one directory to another. Note: it is impossible to Rename() a file from one volume to another. INPUTS oldName - pointer to a null-terminated string newName - pointer to a null-terminated string OUTPUTS success - boolean dos.library/Seek NAME Seek -- Find and point at the logical position in a file SYNOPSIS oldPosition = Seek( file, position, mode ) D0 D1 D2 D3 LONG oldPosition, position, mode; struct FileHandle *file; FUNCTION Seek() sets the read/write cursor for the file 'file' to the position 'position'. This position is used by both Read() and Write() as a place to start reading or writing. The result is the current absolute position in the file, or -1 if an error occurs, in which case IoErr() can be used to find more information. 'mode' can be OFFSET_BEGINNING, OFFSET_CURRENT or OFFSET_END. It is used to specify the relative start position. For example, 20 from current is a position 20 bytes forward from current, -20 is 20 bytes back from current. So that to find out where you are, seek zero from current. The end of the file is a Seek() positioned by zero from end. You cannot Seek() beyond the end of a file. INPUTS file - BCPL pointer to a file handle position - integer mode - integer OUTPUTS oldPosition - integer dos.library/SetComment NAME SetComment -- Change a files' comment string SYNOPSIS success = SetComment( name, comment ) D0 D1 D2 BOOL success; char *name; char *comment; FUNCTION SetComment() sets a comment on a file or directory. The comment is a pointer to a null-terminated string of up to 80 characters. INPUTS name - pointer to a null-terminated string comment - pointer to a null-terminated string dos.library/SetProtection NAME SetProtection -- Set protection for a file or directory SYNOPSIS success = SetProtection( name, mask ) D0 D1 D2:4 BOOL success; char *name; LONG mask; FUNCTION SetProtection() sets the protection attributes on a file or directory. The lower bits of the mask are as follows: Bits 31-4 Reserved. bit 4: 1 = file has not changed 0 = file has been changed bit 3: 1 = reads not allowed, 0 = reads allowed. bit 2: 1 = writes not allowed, 0 = writes allowed. bit 1: 1 = execution not allowed, 0 = execution allowed. bit 0: 1 = deletion not allowed, 0 = deletion allowed. Only delete is checked for by the Old Filing System. The archive bit is cleared by the file system whenever the file is changed. Backup utilities will generally set the bit after backing up each file. The new Fast Filing System looks at the read and write bits, and the Shell looks at the execute bit, and will refuse to start a file as a binary executable if it is set. Other bits may will be defined in the "libraries/dos.h" include files. Rather than referring to bits by number you should use the definitions in "dos.h". INPUTS name - pointer to a null-terminated string mask - the protection mask required OUTPUTS success - boolean dos.library/UnLoadSeg NAME UnLoadSeg -- Unload a segment previously loaded by LoadSeg() SYNOPSIS error = UnLoadSeg( segment ) D0 D1 BOOL error; BPTR segment; FUNCTION Unload a segment loaded by LoadSeg(). 'segment' may be zero. INPUTS segment - BCPL pointer to a segment identifier OUTPUTS error - boolean dos.library/UnLock NAME UnLock -- Unlock a directory or file SYNOPSIS UnLock( lock ) D1 struct FileLock *lock; FUNCTION The filing system lock [obtained from Lock(), DupLock(), or CreateDir()] is removed and deallocated. INPUTS lock - BCPL pointer to a lock NOTE passing zero to UnLock() is harmless dos.library/WaitForChar NAME WaitForChar -- Determine if chars arrive within a time limit SYNOPSIS status = WaitForChar( file, timeout ) D0 D1 D2 BOOL status; struct FileHandle *file; LONG timeout; FUNCTION If a character is available to be read from 'file' within a the time (in microseconds) indicated by 'timeout', WaitForChar() returns -1 (TRUE). If a character is available, you can use Read() to read it. Note that WaitForChar() is only valid when the I/O stream is connected to a virtual terminal device. If a character is not available within 'timeout', a 0 (FALSE) is returned. BUGS Due to a bug in the timer.device in V1.2/V1.3, specifying a timeout of zero for WaitForChar() can cause the unreliable timer & floppy disk operation. INPUTS file - BCPL pointer to a file handle timeout - integer OUTPUTS status - boolean dos.library/Write NAME Write -- Write bytes of data to a file SYNOPSIS returnedLength = Write( file, buffer, length ) D0 D1 D2 D3 LONG returnedLength; struct FileHandle *file; char *buffer; LONG length; FUNCTION Write() writes bytes of data to the opened file 'file'. 'length' indicates the length of data to be transferred; 'buffer' is a pointer to the buffer. The value returned is the length of information actually written. So, when 'length' is greater than zero, the value of 'length' is the number of characters written. Errors are indicated by a value of -1. INPUTS file - BCPL pointer to a file handle buffer - pointer to the buffer length - integer OUTPUTS returnedLength - integer Enhancements for AmigaDos 1.4 by Randell Jesup Legend: > Indicates an existing dos.library routine BOOL means either FALSE or DOSTRUE (-1). ******* dos.library/AllocDosObject ****************************************** * * NAME * AllocDosObject -- Creates a dos object * * SYNOPSIS * ptr = AllocDosObject(type, tags) * D0 D1 D2 * * void *AllocDosObject(ULONG, struct TagItem *) * * FUNCTION * Create one of several dos objects, initializes it, and returns it * to you. Note the DOS_STDPKT returns a pointer to the sp_Pkt of the * structure. * * RESULT * packet - pointer to the object or NULL * ******* dos.library/FreeDosObject ********** * * NAME * FreeDosObject -- Frees an object allocated by AllocDosObject * * SYNOPSIS * FreeDosObject(type, ptr) * D1 D2 * * void FreeDosObject(ULONG, void *) * * FUNCTION * Frees an object allocated by AllocDosObject. Do NOT call for objects * allocated in any other way. * * INPUTS * type - type passed to AllocDosObject * ptr - ptr returned by AllocDosObject * ====================== Packet Level routines: ====================== ******* dos.library/DoPkt ********** * * NAME * DoPkt -- Send a dos packet and wait for reply * * SYNOPSIS * result1 = DoPkt(port,action,arg1,arg2,arg3,arg4,arg5) * D0 D1 D2 D3 D4 D5 D6 D7 * * LONG = DoPkt(struct MsgPort *,LONG,LONG,LONG,LONG,LONG,LONG) * * FUNCTION * Sends a packet to a handler and waits for it to return. Any secondary * return will be available in D1 AND from IoErr(). DoPkt() will work * even if the caller is an exec task and not a process; however it will * be slower, and may fail for some additional reasons, such as being * unable to allocate a signal. DoPkt uses your pr_MsgPort for the reply, * and will call pr_PktWait. * * INPUTS * port - pr_MsgPort of the handler process to send to. * action - the action requested of the filesystem/handler * arg1, arg2, arg3, arg4,arg5 - arguments, depend on the action, may not * be required. * * RESULT * result1 - the value returned in dp_Res1, or FALSE if there was some * problem in sending the packet or recieving it. * * BUGS * Only allows 5 arguments to be specified. For more arguments (packets * support a maximum of 7) create a packet and use SendPkt/WaitPkt. * ******* dos.library/SendPkt ********** * * NAME * SendPkt -- Sends a packet to a handler * * SYNOPSIS * SendPkt(port, packet) * D1 D2 * * void SendPkt(struct MsgPort *,struct DosPacket *) * * FUNCTION * Sends a packet to a handler and does not wait. All fields in the * packet must be initialized before calling this routine. Uses your * pr_MsgPort for the replyport and dp_Port. * * INPUTS * port - pr_MsgPort of handler process to send to. * packet - packet to send, must be initialized and have a message. * ******* dos.library/WaitPkt ********** * * NAME * WaitPkt -- Waits for a packet to arrive at your pr_MsgPort * * SYNOPSIS * packet = WaitPkt() * D0 * * struct DosPacket *WaitPkt(void); * * FUNCTION * Waits for a packet to arrive at your pr_MsgPort. If anyone has * installed a packet wait function in pr_PktWait, it will be called. * The message will be automatically GetMsg()ed so that it is no longer on * the port. It assumes the message is a dos packet. It is NOT * guaranteed to clear the signal for the port. * * RESULT * packet - the packet that arrived at the port (from ln_Name of message). * ******* dos.library/ReplyPkt ********** * * NAME * ReplyPkt -- replies a packet to the person who sent it to you * * SYNOPSIS * ReplyPkt(packet, result1, result2) * D1 D2 D3 * * void ReplyPkt(struct DosPacket *, LONG, LONG) * * FUNCTION * This returns a packet to the process which sent it to you. In * addition, puts your pr_MsgPort address in dp_Port, so using ReplyPkt * again will send the message to you. (This is used in "ping-ponging" * packets between two processes). It uses result 1 & 2 to set the * dp_Res1 and dp_Res2 fields of the packet. * * INPUTS * packet - packet to reply, assumed to set up correctly. * result1 - first result * result2 - secondary result * NOT IMPLEMENTED IN 1.4: # AbortPkt(port) D1 struct MsgPort *port; Aborts all packets who are to be returned to port. Caveats are similar to AbortIO - don't count on immediate aborting of packets, wait for them to actually come back. AbortPkt may not be implemented in 1.4, since there may not be any reasonable method to make it work. =================== Unbuffered File I/O =================== > BPTR Open(char *, long); > void Close(BPTR); Now returns a BOOL: False for failure, non-False for Success. The default file system will guarantee the file writes have been written to the disk. > long Read(BPTR, char *, long); > long Write(BPTR, char *, long); > BPTR Input(void); > BPTR Output(void); > long Seek(BPTR, long, long); > long IsInteractive(BPTR); > long WaitForChar(BPTR, long); ******* dos.library/SetFileSize ********** * * NAME * SetFileSize -- Sets the size of a file * * SYNOPSIS * success = SetFileSize(fh, offset, mode) * D0 D1 D2 D3 * * BOOL SetFileSize(BPTR, LONG, LONG) * * FUNCTION * Changes the file size, truncating or extending as needed. Not all * handlers will support this; be careful and check the return code. If * the file is extended, no values should be assumed for the new bytes. * * INPUTS * fh - File to be truncated. * offset - Offset from position determined by mode. * mode - One of OFFSET_BEGINNING, OFFSET_CURRENT, or OFFSET_END. * * RESULT * success - Success/failure indicator * ******* dos.library/LockRecord ********** * * NAME * LockRecord -- Locks a portion of a file * * SYNOPSIS * success = LockRecord(fh,offset,length,mode,timeout) * D0 D1 D2 D3 D4 D5 * * ULONG LockRecord(BPTR,ULONG,ULONG,ULONG,ULONG) * * FUNCTION * This locks a portion of a file for exclusive access. * Timeout is how long to wait in ticks (1/50 sec) for the record to be * available. * Valid modes are: * REC_EXCLUSIVE * REC_EXCLUSIVE_IMMED * REC_SHARED * REC_SHARED_IMMED * For the IMMEDIATE modes, timeout is ignored. * * INPUTS * fh - File handle for which to lock the record * offset - Record start position * length - Length of record in bytes * mode - Type of lock requester * timeout - Timeout interval. 0 is legal. * * RESULT * success - Success or failure * ******* dos.library/LockRecords ********** * * NAME * LockRecords -- Lock a series of records * * SYNOPSIS * success = LockRecords(record_array,timeout) * D0 D1 D2 * * BOOL LockRecords(struct RecordLock *,ULONG) * * FUNCTION * This locks several records within a file for exclusive access. * Timeout is how long to wait in ticks for the records to be available. * The wait is pplied to each attempt to lock each record in the list. * * INPUTS * record_array - List of records to be locked * timeout - Timeout interval. 0 is legal * * RESULT * success - Success or failure * ******* dos.library/UnLockRecord ********** * * NAME * UnLockRecord -- Unlock a record * * SYNOPSIS * success = UnLockRecord(fh,offset,length) * D0 D1 D2 D3 * * BOOL UnLockRecord(BPTR,ULONG,ULONG) * * FUNCTION * This releases the specified lock on a file. Note that you must use * the same filehandle you used to lock the record, and offset and length * must be the same values used to lock it. Every LockRecord call must be * balanced with an UnLockRecord call. * * INPUTS * fh - File handle of locked file * offset - Record start position * length - Length of record in bytes * * RESULT * success - Success or failure. * ******* dos.library/UnLockRecords ********** * * NAME * UnLockRecords -- Unlock a list of records * * SYNOPSIS * success = UnLockRecords(record_array) * D0 D1 * * BOOL UnLockRecords(struct RecordLock *) * * FUNCTION * This releases an array of record locks obtained using LockRecords. * You should NOT modify the record_array while you have the records * locked. Every LockRecords call must be balanced with an UnLockRecords * call. * * INPUTS * record_array - List of records to be unlocked * * RESULT * success - Success or failure. * ================= Buffered File I/O ================= ******* dos.library/SelectInput ********** * * NAME * SelectInput -- Select a filehandle as the default input channel * * SYNOPSIS * old_fh = SelectInput(fh) * D0 D1 * * BPTR SelectInput(BPTR) * * FUNCTION * Set the current input as the default input for the process. * This changes the value returned by Input(). old_fh should * be closed or saved as needed. * * INPUTS * fh - Newly default input handle * * RESULT * old_fh - Previous default input filehanldle * ******* dos.library/SelectOutput ********** * * NAME * SelectOutput -- Select a filehandle as the default input channel * * SYNOPSIS * old_fh = SelectOutput(fh) * D0 D1 * * BPTR SelectOutput(BPTR) * * FUNCTION * Set the current output as the default output for the process. * This changes the value returned by Output(). old_fh should * be closed or saved as needed. * * INPUTS * fh - Newly desired output handle * * RESULT * old_fh - Previous current output * ******* dos.library/FGetC ********** * * NAME * FGetC -- Read a character from the specified input channel (buffered) * * SYNOPSIS * char = FGetC(fh) * D0 D1 * * LONG FGetC(BPTR) * * FUNCTION * Reads the next character from the input stream. A -1 is * returned when EOF or an error is encountered. * * INPUTS * fh - filehandle to use for buffered I/O * * RESULT * char - character read (0-255) or -1 * ******* dos.library/FPutC ********** * * NAME * FPutC -- Write a character to the specified output channel (buffered) * * SYNOPSIS * success = FPutC(fh, char) * D0 D1 D2 * * BOOL FPutC(BPTR, UBYTE) * * FUNCTION * Writes a single character to the output stream. * * INPUTS * fh - filehandle to use for buffered I/O * char - character to write * * RESULT * success - success/failure flag * * BUGS * Doesn't return success code yet * ******* dos.library/UnGetC ********** * * NAME * UnGetC -- Makes a character available for reading again. (buffered) * * SYNOPSIS * value = UnGetC(fh, character) * D0 D1 D2 * * LONG UnGetC(BPTR, LONG) * * FUNCTION * Pushes the character specified back into the input buffer. Every * time you use a buffered read routine, you can always push back 1 * character. You may be able to push back more, though it is not * recommended, since there is no guarantee on how many can be * pushed back at a given moment. * Passing -1 for the character will cause the last character read to * be pushed back. * * INPUTS * fh - filehandle to use for buffered I/O * character - character to push back or -1 * * RESULT * value - character pushed back, or FALSE if the character cannot * be pushed back. * ******* dos.library/FRead ********** * * NAME * FRead -- Reads a number of blocks from an input channel (buffered) * * SYNOPSIS * count = FRead(fh, buf, blocklen, blocks) * D0 D1 D2 D3 D4 * * LONG FRead(BPTR, UBYTE *, ULONG, ULONG) * * FUNCTION * Attempts to read a number of blocks, each blocklen long, into the * specified buffer from the input stream (buffered). May return less * than the number of blocks requested, either due to EOF or when input * is an interactive stream. A return of -1 indicates an error. * * INPUTS * fh - filehandle to use for buffered I/O * buf - Area to read bytes into. * blocklen - number of bytes per block. Must be > 0. * blocks - number of blocks to read. Must be > 0. * * RESULT * count - Number of _blocks_ read, or 0 for EOF, or -1 for error. * ******* dos.library/FWrite ********** * * NAME * FWrite -- Writes a number of blocks to an output channel (buffered) * * SYNOPSIS * count = FWrite(fh, buf, blocklen, blocks) * D0 D1 D2 D3 D4 * * LONG FWrite(BPTR, UBYTE *, ULONG, ULONG) * * FUNCTION * Attempts to write a number of blocks, each blocklen long, from the * specified buffer to the output stream (buffered). May return less * than the number of blocks requested, if there is some error such * as a full disk or r/w error. A return of -1 indicates an error. * * INPUTS * fh - filehandle to use for buffered I/O * buf - Area to write bytes from. * blocklen - number of bytes per block. Must be > 0. * blocks - number of blocks to read. Must be > 0. * * RESULT * count - Number of _blocks_ written, or -1 for error. * ******* dos.library/FGets ********** * * NAME * FGets -- Reads a line from the specified input channel (buffered) * * SYNOPSIS * count = FGets(fh, buf, len) * D0 D1 D2 D3 * * LONG FGets(BPTR, UBYTE *, ULONG) * * FUNCTION * This routine reads in a single line from the specified input stopping * at a NEWLINE character or EOF. In either event, UP TO the number of * len specified bytes will be copied into the buffer. Hence if a length * of 50 is passed and the input line is longer than 50 bytes, it will * return 50 characters. The returned length indicates the number of bytes * put into the buffer. If terminated by a newline, the newline WILL be * the last character in the bytes read. This is a buffered read routine. * The characters read in are NOT null-terminated. * * INPUTS * fh - filehandle to use for buffered I/O * buf - Area to read bytes into. * len - Number of bytes to read, must be > 0. * * RESULT * count - Number of bytes read, or 0 for immediate EOF, or -1 for error. * ******* dos.library/FPuts ********** * * NAME * FPuts -- Writes a string the the specified output channel (buffered) * * SYNOPSIS * count = FPuts(fh, str) * D0 D1 D2 * * LONG FPuts(BPTR, UBYTE *) * * FUNCTION * This routine writes an unformatted string to the filehandle. No * newline is appended to the string and the length is returned. * * INPUTS * fh - filehandle to use for buffered I/O * str - Null-terminated string to be written to default output * * RESULT * count - Number of bytes written. -1 indicates an error * ******* dos.library/PutStr ********** * * NAME * PutStr -- Writes a string the the default output channel (buffered) * * SYNOPSIS * count = PutStr(str) * D0 D1 * * LONG PutStr(UBYTE *) * * FUNCTION * This routine writes an unformatted string to the default output. No * newline is appended to the string and the length is returned. * * INPUTS * str - Null-terminated string to be written to default output * * RESULT * count - Number of bytes written. -1 indicates an error * ******* dos.library/VPrintf ********** * * NAME * VPrintf -- format and print string (buffered) * * SYNOPSIS * count = VPrintf(fmt, argv) * D0 D1 D2 * * LONG VPrintf(char *, long[]) * * FUNCTION * Writes the formatted string and values to Output(). This routine is * assumed to handle all internal buffering so that the formatting string * and resultant formatted values can be arbitrarily long. Any secondary * error code is returned in IoErr(). * * INPUTS * fmt - RawDoFmt style formatting string * argv[] - Pointer to array of formatting values * * RESULT * count - Number of bytes written or -1 for error * ******* dos.library/VFPrintf ********** * * NAME * VFPrintf -- format and print a string to a file (buffered) * * SYNOPSIS * count = VFPrintf(fh, fmt, argv) * D0 D1 D2 D3 * * LONG VFPrintf(BPTR, char *, long[]) * * FUNCTION * Writes the formatted string and values to the given file. This * routine is assumed to handle all internal buffering so that the * formatting string and resultant formatted values can be arbitrarily * long. Any secondary error code is returned in IoErr(). * * INPUTS * fh - File to write to * fmt - RawDoFmt style formatting string * argv[] - Pointer to array of formatting values * * RESULT * count - Number of bytes written or -1 for error * ******* dos.library/VFWritef *************** * * NAME * VFWritef - write a BCPL formatted string to a filehandle (buffered) * * SYNOPSIS * count = VFWritef(fh, fmt, argv) * D0 D1 D2 D3 * * LONG VFWritef(BPTR, char *, LONG *) * * FUNCTION * Writes the formatted string and values to the default output. This * routine is assumed to handle all internal buffering so that the * formatting string and resultant formatted values can be arbitrarily * long. The formats are in BCPL form. * * INPUTS * fmt - BCPL style formatting string * argv - Pointer to array of formatting values * * RESULT * count - Number of bytes written or -1 for error * ******* dos.library/Flush ************ * * NAME * Flush -- Flushes a writes to a buffered filehandle * * SYNOPSIS * success = Flush(fh) * D0 D1 * * BOOL Flush(BPTR) * * FUNCTION * Flushes any pending buffered writes to the filehandle. All buffered * writes will also be flushed on Close(). * * INPUTS * fh - Filehandle to flush. * * RESULT * success - Success of failure. * ================= Object Management ================= > long DeleteFile(char *); > long Rename(char *, char *); > BPTR Lock(char *, long); > void UnLock(BPTR); > BPTR DupLock(BPTR); > long Examine(BPTR, struct FileInfoBlock *); > long ExNext(BPTR, struct FileInfoBlock *); > long Info(BPTR, struct InfoData *); > BPTR CreateDir(char *); > long SetComment(char *, char *); > long SetProtection(char *, long); > BPTR ParentDir(BPTR); ******* dos.library/ChangeMode ************ * * NAME * ChangeMode - Change the current mode of a lock or filehandle * * SYNOPSIS * success = ChangeMode(type, object, newmode) * D0 D1 D2 D3 * * BOOL ChangeMode(ULONG, BPTR, ULONG) * * FUNCTION * This allows you to attempt to change the mode in use by a lock or * filehandle. For example, you could attempt to turn a shared lock * into an exclusive lock. The handler may well reject this request. * Warning: if you use the wrong type for the object, the system may * crash. * * INPUTS * type - Either CHANGE_FH or CHANGE_LOCK * object - A lock or filehandle * newmode - The new mode you want * * RESULT * success - Boolean * ******* dos.library/DupLockFromFH ****************** * * NAME * DupLockFromFH -- Gets a lock on an open file * * SYNOPSIS * lock = DupLockFromFH(fh) * D0 D1 * * BPTR DupLockFromFH(BPTR) * * FUNCTION * Obtain a lock on the object associated with fh. Only works if the * file was opened using a non-exclusive mode. * * INPUTS * fh - Opened file for which to obtain the lock * * RESULT * lock - Obtained lock or NULL for failure * ******* dos.library/OpenFromLock ************ * * NAME * OpenFromLock -- Opens a file you have a lock on * * SYNOPSIS * fh = OpenFromLock(lock,mode) * D0 D1 D2 * * BPTR OpenFromLock(BPTR,LONG) * * FUNCTION * Given a lock, this routine performs an open on that lock. You must not * UnLock the lock until you Close the file! * * INPUTS * lock - Lock on object to be opened. * mode - Type of Open() - see Open() * * RESULT * fh - Newly opened file handle or NULL for failure. * ******* dos.library/ParentOfFH ************ * * NAME * ParentOfFH -- returns a lock on the parent directory of an open file * * SYNOPSIS * lock = ParentOfFH(fh) * D0 D1 * * BPTR ParentOfFH(BPTR) * * FUNCTION * Returns a shared lock on the parent directory of the filehandle. * * INPUTS * fh - Filehandle you want the parent of. * * RESULT * lock - Lock on parent directory of the filehandle or NULL for failure. * ******* dos.library/ExamineFH ************ * * NAME * ExamineFH -- Gets information on an open file * * SYNOPSIS * rc = ExamineFH(fh, fib) * D0 D1 D2 * * BOOL ExamineFH(BPTR, struct FileInfoBlock *) * * FUNCTION * Examines a filehandle and returns information about the file in the * FileInfoBlock. * * INPUTS * fh - Filehandle you wish to examine * fib - Must be longword aligned. * * RESULT * rc - Success/failure indication * ******* dos.library/SetFileDate ************ * * NAME * SetFileDate -- Sets the modification date for a file or directory * * SYNOPSIS * rc = SetFileDate(name, date) * D0 D1 D2 * * BOOL SetFileDate(char *, struct DateStamp *) * * FUNCTION * Sets the file date for a file or directory. Note that for the Old * File System and the Fast File System, the date of the root directory * cannot be set. Other filesystems may not support setting the date * for all files/directories. * * INPUTS * name - Name of object * date - New modification date * * RESULT * rc - Success/failure indication * ******* dos.library/NameFromLock ************ * * NAME * NameFromLock -- Returns the name of a locked object * * SYNOPSIS * rc = NameFromLock(lock, buffer, len) * D0 D1 D2 D3 * * BOOL NameFromLock(BPTR, char *, LONG) * * FUNCTION * Returns a fully qualified path for the lock. This routine is * guaranteed not to write more than len characters into the buffer. The * name will be null-terminated. * * INPUTS * lock - Lock of object to be examined. * buffer - Buffer to store name. * len - Length of buffer. * * RESULT * rc - Success/failure indicator. * ******* dos.library/NameFromFH ************ * * NAME * NameFromFH -- Return the name of an object associated with a filehandle * * SYNOPSIS * rc = NameFromFH(fh, buffer, len) * D0 D1 D2 D3 * * BOOL NameFromFH(BPTR, char *, LONG) * * FUNCTION * Returns a fully qualified path for the filehandle. This routine is * guaranteed not to write more than len characters into the buffer. The * name will be null-terminated. * * INPUTS * fh - Lock of object to be examined. * buffer - Buffer to store name. * len - Length of buffer. * * RESULT * rc - Success/failure indicator. * ******* dos.library/SplitName ************ * * NAME * SplitName -- splits out a component of a pathname into a buffer * * SYNOPSIS * newpos = SplitName(name, separator, buf, oldpos, size) * D0 D1 D2 D3 D4 D5 * * WORD SplitName(UBYTE *, UBYTE, UBYTE *, WORD, LONG) * * FUNCTION * This routine splits out the next piece of a name from a given file * name. Each piece is copied into the buffer, truncating at size-1 * characters. The new position is then returned so that it may be * passed in to the next call to splitname. If the separator is not * found within 'size' characters, then size-1 characters plus a null will * be put into the buffer, and the position of the next separator will * be returned. * If a a separator cannot be found, -1 is returned (but the characters * from the old position to the end of the string are copied into the * buffer, up to a maximum of size-1 characters). Both strings are * null-terminated. * * INPUTS * name - Filename being parsed. * separator - Separator charactor to split by. * buf - Buffer to hold separated name. * oldpos - Current position in the file. * size - Size of buf in bytes (including null termination); * * RESULT * newpos - New position for next call to splitname. -1 for last one. * ******* dos.library/SameLock ************ * * NAME * SameLock -- returns whether two locks are on the same object. * * SYNOPSIS * value = SameLock(lock1, lock2) * D0 D1 D2 * * LONG SameLock(BPTR, BPTR) * * FUNCTION * Compares two locks. Returns LOCK_SAME if they are on the same object, * LOCK_SAME_HANDLER if on different objects on the same handler, and * LOCK_DIFFERENT if they are on different handlers. * * INPUTS * lock1 - 1st lock for comparison * lock2 - 2nd lock for comparison * * RESULT * value - LOCK_SAME, LOCK_SAME_HANDLER, LOCK_DIFFERENT * ******* dos.library/ExAll ************ * * NAME * ExAll -- Examine an entire directory * * SYNOPSIS * success = ExAll(lock, buffer, size, type, control) * D0 D1 D2 D3 D4 D5 * * BOOL ExAll(BPTR,UBYTE *,LONG,LONG,struct ExAllControl *) * * FUNCTION * Examines an entire directory. * * Lock must be on a directory. Size is the size of the buffer supplied. * The buffer will be filled with (partial) ExAllData structures, as * specified by the type field. * * Type is a value from those shown below that determines which information is * to be stored in the buffer. Each higher value adds a new thing to the list * as described in the table below:- * * ED_NAME FileName * ED_TYPE Type * ED_SIZE Size in bytes * ED_PROTECTION Protection bits * ED_DATE 3 longwords of date * ED_COMMENT Comment (will be NULL if no comment) * * Thus, ED_NAME gives only filenames, and ED_COMMENT gives everything. * * The control structure is required so that FFS can keep track if more than * one call to ExAll is required. This happens when there are more names in * a directory than will fit into the buffer. The format of the control * structure is as follows:- * * NOTE: the control structure MUST be allocated by AllocDosObject!!! * * Entries: This field tells the calling application how many entries are * in the buffer after calling ExAll. * * LastKey: This field ABSOLUTELY MUST be initialised to 0 before calling * ExAll for the first time. Any other value will cause nasty * things to happen. If ExAll doesn't return ERROR_NO_MORE_ENTRIES, * then this field should not be touched before making the second * and subsequent calls to ExAll. Whenever ExAll returns TRUE, there * are more calls required before all names have been received. * As soon as a FALSE return is received (and IOErr says no_more..) * then ExAll has completed. * * MatchString * if this field is NULL then all filenames will be returned. If * this field is non-null then it is interpreted as a pointer to * a string that is used to pattern match all file names before * accepting them and putting them into the buffer. The default * AmigaDOS pattern match routine is used unless...... * * MatchFunc: * Contains a pointer to a hook for a routine to decide if the entry * will be included in the returned list of entries. The entry is * filled out first, and then passed to the hook. If no MatchFunc is * to be called then this entry should be NULL. The hook is * called with the following parameters (as is standard for hooks): * * BOOL = MatchFunc( hookptr, data, typeptr ) * a0 a1 a2 * (a0 = ptr to hook, a1 = ptr to filled in ExAllData, a2 = ptr * to longword of type). * * MatchFunc should return FALSE if the entry is not to be * accepted, otherwise return TRUE. * * INPUTS * lock - Lock on directory to be examined. * ... * * RESULT * success - Success/failure of the call. * ============== Error Handling ============== > long IoErr(void); ******* dos.library/SetIoErr ************ * * NAME * SetIoErr -- Sets the value returned by IoErr() * * SYNOPSIS * SetIoErr(code) * D1 * * void SetIoErr(LONG); * * FUNCTION * This routine sets up the secondary result (pr_Result2) return code * (returned by the IoErr() function). * * INPUTS * code - Code to be returned by a call to IoErr. * ******* dos.library/Fault ************ * * NAME * Fault -- Returns the text associated with a DOS error code * * SYNOPSIS * rc = Fault(code, header, buffer, len) * D0 D1 D2 D3 D4 * * BOOL Fault(LONG, UBYTE *, UBYTE *, LONG) * * FUNCTION * This routine obtains the error message text for the given error code. * The header is prepended to the text of the error message, followed * by a colon. Requires the program C:Fault to exist. Puts a null- * terminated string for the error message into the buffer. By convention, * error messages should be no longer than 80 characters (+1 for termin- * ation), and preferably no more than 60. * The value returned by IoErr() is set to the code passed in. * * INPUTS * code - Error code * header - header to output before error text * buffer - Buffer to receive error message. MUST BE LONGWORD ALIGNED! * len - Length of the buffer. * * RESULT * rc - Success/failure code. On failure, the text for the error * message will be "Error code <number>\n". * ******* dos.library/PrintFault ************ * * NAME * PrintFault -- Returns the text associated with a DOS error code * * SYNOPSIS * rc = PrintFault(code, header) * D0 D1 D2 * * BOOL PrintFault(LONG, UBYTE *) * * FUNCTION * This routine obtains the error message text for the given error code. * This is similar to the Fault() function, except that the output is * written to the default output channel with buffered output. * The value returned by IoErr() is set to the code passed in. * * INPUTS * code - Error code * header - header to output before error text * * RESULT * rc - Success/failure code. On failure, the text for the error * message will be "Error code <number>\n". * ******* dos.library/ErrorReport ************ * * NAME * ErrorReport -- Displays a Retry/Cancel requester for an error code * * SYNOPSIS * status = ErrorReport(code, type, arg1, device) * D0 D1 D2 D3 A0 * * BOOL ErrorReport(LONG, LONG, ULONG, struct MsgPort *) * * FUNCTION * Based on the request type, this routine formats the appropriate * requester to be displayed. If the code is not understood, it returns * DOS_TRUE immediately. Returns DOS_TRUE if the user selects CANCEL or * if the attempt to put up the requester fails, or if the process * pr_WindowPtr is -1. Returns FALSE if the user selects Retry. The * routine will retry on DISKINSERTED for appropriate error codes. * * INPUTS * code - Error code to put a requester up for. * Current valid error codes are: * ERROR_DISK_NOT_VALIDATED * ERROR_DISK_WRITE_PROTECTED * ERROR_DISK_FULL * ERROR_DEVICE_NOT_MOUNTED * ERROR_NOT_A_DOS_DISK * ERROR_NO_DISK * ABORT_DISK_ERROR /* read/write error */ * ABORT_BUSY /* you MUST replace... */ * type - Request type: * REPORT_LOCK - arg1 is a lock (BPTR). * REPORT_FH - arg1 is a filehandle (BPTR). * REPORT_VOLUME - arg1 is a volumenode (C pointer). * arg1 - variable parameter (see type) * device - (Optional) Address of handler task for which report is to be * made. Only required for REPORT_LOCK, and only if arg1==NULL. * * RESULT * status - Cancel/Retry indicator (DOS_TRUE == Cancel) * ================== Process Management ================== > struct MsgPort *CreateProc(char *, long, BPTR, long); (Obsolete, see CreateNewProc) > long Execute(char *, BPTR, BPTR); > void Exit(long); > BPTR CurrentDir(BPTR); ******* dos.library/Cli ************ * * NAME * Cli -- Returns a pointer to the CLI structure of the current process. * * SYNOPSIS * cli_ptr = Cli() * D0 * * struct CommandLineInterface *Cli(void) * * FUNCTION * Returns a pointer to the CLI structure of the current process, or NULL * if the process has no CLI structure. * * RESULT * cli_ptr - pointer to the CLI structure. * ******* dos.library/CreateNewProc ************ * * NAME * CreateNewProc -- Create a new process * * SYNOPSIS * process = CreateNewProc(tags) * D0 D1 * * struct Process *CreateNewProc(struct TagItem *) * * FUNCTION * This creates a new process according to the specification of the newproc * structure. See libraries/dostags.h for the NewProcess tags. * * INPUTS * tags - a pointer to a TagItem array. * * RESULT * process - The created process. * ******* dos.library/RunCommand ************ * * NAME * RunCommand -- Runs a program using the current process * * SYNOPSIS * rc = RunCommand(seglist, stacksize, argptr, argsize) * D0 D1 D2 D3 D4 * * LONG RunCommand(BPTR, ULONG, char *, ULONG) * * FUNCTION * Runs a command on your process/cli. Seglist may be any language, * including BCPL programs. Stacksize is in longs. argptr is a null- * terminated string, argsize is its length. Returns returncode the * program exited with. Returns -1 if stack couldn't be allocated. * * INPUTS * seglist - Seglist of command to run. * stacksize - Number of bytes to allocate for stack space * argptr - Pointer to argument command string. * argsize - Number of bytes in argument command. * * RESULT * rc - Return code from executed command. -1 indicates failure * ******* dos.library/GetConsoleTask ************ * * NAME * GetConsoleTask -- Returns the default console for the process * * SYNOPSIS * port = GetConsoleTask() * D0 * * struct MsgPort *GetConsoleTask(void) * * FUNCTION * Returns the default console task's port (pr_ConsoleTask) for the * current process. * * RESULT * port - The pr_MsgPort of the console handler, or NULL. * ******* dos.library/SetConsoleTask ************ * * NAME * SetConsoleTask -- Sets the default console for the process * * SYNOPSIS * SetConsoleTask(port) * D1 * * void SetConsoleTask(struct MsgPort *) * * FUNCTION * Sets the default console task's port (pr_ConsoleTask) for the * current process. * * INPUTS * port - The pr_MsgPort of the console handler. * ******* dos.library/GetFileSysTask ************ * * NAME * GetFileSysTask -- Returns the default filesystem for the process * * SYNOPSIS * port = GetFileSysTask() * D0 * * struct MsgPort *GetFileSysTask(void) * * FUNCTION * Returns the default filesystem task's port (pr_FileSystemTask) for the * current process. * * RESULT * port - The pr_MsgPort of the filesystem, or NULL. * ******* dos.library/SetFileSysTask ************ * * NAME * SetFileSysTask -- Sets the default filesystem for the process * * SYNOPSIS * SetFileSysTask(port) * D1 * * void SetFileSysTask(struct MsgPort *) * * FUNCTION * Sets the default filesystem task's port (pr_FileSystemTask) for the * current process. * * INPUTS * port - The pr_MsgPort of the filesystem * ******* dos.library/GetArgStr ************ * * NAME * GetArgStr -- Returns the arguments for the program (process) * * SYNOPSIS * ptr = GetArgStr() * D0 * * UBYTE *GetArgStr(void) * * FUNCTION * Returns a pointer to the (null-terminated) arguments for the program * (process). This is the same string passed in a0 on startup from CLI. * * RESULT * ptr - pointer to arguments * ******* dos.library/SetArgStr ************ * * NAME * SetArgStr -- Sets the arguments for the current program (process) * * SYNOPSIS * SetArgStr(ptr) * D1 * * void SetArgStr(UBYTE *) * * FUNCTION * Sets the arguments for the current program. The ptr MUST be reset * to it's original value before process exit. * * INPUTS * ptr - pointer to new argument string. * ******* dos.library/FindCliProc ************ * * NAME * FindCliProc -- returns a pointer to the requested CLI process * * SYNOPSIS * proc = FindCliProc(num) * D0 D1 * * struct Process *FindCliProc(LONG) * * FUNCTION * This routine returns a pointer to the CLI process associated with the * given CLI number. If no task is active, NULL is returned. NOTE: should * normally be called inside a Forbid(), if you must use this function at * all. (Note: I don't like the forbid bit, maybe a semaphore is a good * idea, or some other way to get the information needed - probably will * change). * * INPUTS * num - CLI process of interest. * * RESULT * proc - Pointer to given CLI process * ******* dos.library/MaxCli ************ * * NAME * MaxCli -- returns the highest CLI process number possibly in use. * * SYNOPSIS * number = MaxCli() * D0 * * LONG MaxCli(void) * * FUNCTION * Returns the highest CLI number that may be in use. CLI numbers are * reused, and are usually as small as possible. To find all CLIs, scan * using FindCLI from 1 to MaxCLI(). The number returned by MaxCli may * change as processes are created and destroyed. * * RESULT * number - The highest CLI number that may be in use. * ******* dos.library/SetCurrentDirName ************ * * NAME * SetCurrentDirName -- Sets the current directory name for the process * * SYNOPSIS * success = SetCurrentDirName(name) * D0 D1 * * BOOL SetCurrentDirName(char *) * * FUNCTION * Sets the name for the current dir in the cli structure. If the name is * too long to fit, a failure is returned, and the old value is left * intact. It is advised that you inform the user of this condition. * This routine is safe to call even if there is no CLI structure. * * INPUTS * name - Name of directory to be set. * * RESULT * success - Success/failure indicator * ******* dos.library/GetCurrentDirName ************ * * NAME * GetCurrentDirName -- returns the current directory name * * SYNOPSIS * success = GetCurrentDirName(buf, len) * D0 D1 D2 * * BOOL GetCurrentDirName(char *, LONG) * * FUNCTION * Extracts the current directory name from the CLI structure and puts it * into the buffer. If the buffer is too small, the name is truncated * appropriately and a failure code returned. If no CLI structure is * present, a null name is returned. * * INPUTS * buf - Buffer to hold extracted name * len - Number of bytes of space in buffer * * RESULT * success - Success/failure indicator * ******* dos.library/SetProgramName ************ * * NAME * SetProgramName -- Sets the name of the program being run * * SYNOPSIS * success = SetProgramName(name) * D0 D1 * * BOOL SetProgramName(char *) * * FUNCTION * Sets the name for the program in the cli structure. If the name is * too long to fit, a failure is returned, and the old value is left * intact. It is advised that you inform the user if possible of this * condition, and/or set the program name to an empty string. * This routine is safe to call even if there is no CLI structure. * * INPUTS * name - Name of program to use. * * RESULT * success - Success/failure indicator. * ******* dos.library/GetProgramName ************ * * NAME * GetProgramName -- Returns the current program name * * SYNOPSIS * success = GetProgramName(buf, len) * D0 D1 D2 * * BOOL GetProgramName(char *, LONG) * * FUNCTION * Extracts the program name from the CLI structure and puts it * into the buffer. If the buffer is too small, the name is truncated * appropriately and a failure code returned. If no CLI structure is * present, a null name is returned. * * INPUTS * buf - Buffer to hold extracted name * len - Number of bytes of space in buffer * * RESULT * success - Success/failure indicator * ******* dos.library/SetPrompt ************ * * NAME * SetPrompt -- Sets the CLI/shell prompt for the current process * * SYNOPSIS * success = SetPrompt(name) * D0 D1 * * BOOL SetPrompt(char *) * * FUNCTION * Sets the text for the prompt in the cli structure. If the prompt is * too long to fit, a failure is returned, and the old value is left * intact. It is advised that you inform the user of this condition. * This routine is safe to call even if there is no CLI structure. * * INPUTS * name - Name of prompt to be set. * * RESULT * success - Success/failure indicator. * ******* dos.library/GetPrompt ************ * * NAME * GetPrompt -- Returns the prompt for the current process * * SYNOPSIS * success = GetPrompt(buf, len) * D0 D1 D2 * * BOOL GetPrompt(char *, LONG) * * FUNCTION * Extracts the prompt string from the CLI structure and puts it * into the buffer. If the buffer is too small, the string is truncated * appropriately and a failure code returned. If no CLI structure is * present, a null string is returned. * * INPUTS * buf - Buffer to hold extracted prompt * len - Number of bytes of space in buffer * * RESULT * success - Success/failure indicator * ******* dos.library/GetProgramDir ************ * * NAME * GetProgramDir -- Returns a lock on the directory the program was loaded * from. * * SYNOPSIS * lock = GetProgramDir() * D0 * * BPTR GetProgramDir(void) * * FUNCTION * Returns a shared lock on the directory the program was loaded from. * This can be used for a program to find data files, etc, that are stored * with the program, or to find the program file itself. NULL returns are * valid, and may occur, for example, when running a program from the * resident list. You should NOT unlock the lock. * * RESULT * lock - A lock on the directory the current program was loaded from, * or NULL if loaded from resident list, etc. * * BUGS * Should return a lock for things loaded via resident * ******* dos.library/SetProgramDir ************ * * NAME * SetProgramDir -- Sets the directory returned by GetProgramDir * * SYNOPSIS * SetProgramDir(lock) * D1 * * void SetProgramDir(BPTR) * * FUNCTION * Sets a shared lock on the directory the program was loaded from. * This can be used for a program to find data files, etc, that are stored * with the program, or to find the program file itself. NULL is a * valid input. * * INPUTS * lock - A lock on the directory the current program was loaded from * ******* dos.library/System ************ * * NAME * System -- Have the default CLI execute a command line * * SYNOPSIS * error = System(command, tags) * D0 D1 D2 * * LONG System(UBYTE *, struct TagItem *) * * FUNCTION * Similar to Execute, but does not read commands from the input * filehandle. Spawns a CLI process to execute the command, and returns * the returncode the command produced, or -1 if the command could not be * run for any reason. The input and output filehandles will not be * closed by System, you must close them (if needed) after System returns. * To make it inherit your input or output, use Input() or Output() for * the filehandle. Normal CLI command-line parsing will be done, * including redirection. The current directory and path will be * inherited from your process. Your path will be used to find the * command. * * INPUTS * command - Program and arguments * tags - see dos/dostags.h. Currently allows specifying input and * output filehandles. * * RESULT * error - 0 for success, error from command, or -1. * ====================== Device List Management ====================== > struct MsgPort *DeviceProc(char *); Bumps an open count (see CloseDeviceProc()). ******* dos.library/AssignLock ************ * * NAME * AssignLock -- Creates an assignment to a locked object * * SYNOPSIS * rc = AssignLock(name,lock) * D0 D1 D2 * * BOOL AssignLock(char *,BPTR) * * FUNCTION * Sets up an assign of a name to a given lock. Passing NULL for a lock * cancels any outstanding assign to that name. If an assign entry of * that name is already on the list, this routine replaces that entry. If * an entry is on the list that conflicts with the new assign, then a * failure code is returned. * * INPUTS * name - Name of device to assign lock to (without trailing ':') * lock - Lock associated with the assigned name * * RESULT * rc - Success/failure indicator * ******* dos.library/AssignPath ************ * * NAME * AssignPath -- Creates an assignment to a specified path * * SYNOPSIS * rc = AssignPath(name,path) * D0 D1 D2 * * BOOL AssignPath(char *,char *) * * FUNCTION * Sets up a assignment that is expanded upon EACH reference to the name. * This is implemented through a new device list type (DLT_ASSIGNPATH, or * some such). The path (a string) would be attached to the node. When * the name is referenced (Open("FOO:xyzzy"...), the string will be used * to determine where to do the open. No permanent lock will be part of * it. For example, you could AssignPath c2: to df2:c, and references to * c2: would go to df2:c, even if you change disks. * * The other major advantage is assigning things to unmounted volumes, * which will be requested upon access (useful in startup sequences). * * INPUTS * name - Name of device to be assigned (without trailing ':') * path - Name of late assignment to be resolved at each reference * * RESULT * rc - Success/failure indicator of the operation * ******* dos.library/GetDeviceProc ************ * * NAME * GetDeviceProc -- Finds a handler to send a message to * * SYNOPSIS * devproc = GetDeviceProc(name, devproc) * D0 D1 D2 * * struct DevProc *GetDeviceProc(UBYTE *, struct DevProc *) * * FUNCTION * Finds the handler/filesystem to send packets regarding 'name' to. * This may involve getting temporary locks. It returns a structure * that includes a lock and msgport to send to to attempt your operation. * It also includes information on how to handle multiple-directory * assigns (by passing the DevProc back to GetDeviceProc until it returns * NULL). * * The initial call to GetDeviceProc should pass NULL for devproc. If * after using the returned DevProc, you get an ERROR_OBJECT_NOT_FOUND, * and (devproc->dvp_Flags & DVPF_ASSIGN) is true, you should call * GetDeviceProc again, passing it the devproc structure. It will either * return a modified devproc structure, or NULL (with ERROR_NO_MORE_ENTRIES * in IoErr()). * * Increments the counter that locks a handler/fs into memory. After * calling FreeDeviceProc, do not use the port or lock again! * * INPUTS * name - name of the object you wish to access * devproc - A value returned by GetDeviceProc before, or NULL * * RESULT * devproc - a pointer to a DevProc structure or NULL * ******* dos.library/FreeDeviceProc ************ * * NAME * FreeDeviceProc -- Releases hold on port returned by GetDeviceProc * * SYNOPSIS * FreeDeviceProc(devproc) * D1 * * void FreeDeviceProc(struct DevProc *) * * FUNCTION * Frees up the structure created by GetDeviceProc, and any associated * temporary locks. * Decrements the counter incremented by GetDeviceProc. The counter is in * an extension to the 1.3 process structure. After calling * FreeDeviceProc, do not use the port or lock again! It is safe to call * FreeDeviceProc(NULL). * * INPUTS * devproc - A value returned by GetDeviceProc * ******* dos.library/LockDosList ************ * * NAME * LockDosList -- Locks the Dos Lists for use * * SYNOPSIS * dlist = LockDosList(flags) * D0 D1 * * struct DosList *LockDosList(ULONG) * * FUNCTION * Locks the dos device list in preparation to walk the list. * If the list is 'busy' then this routine will not return until it is * available. This routine "nests": you can call it multiple times, and * then must unlock it the same number of times. The dlist * returned is NOT a valid entry: it is a special value. Note that * for 1.3 compatibility, it also does a Forbid() - this will probably * be removed at some future time. The 1.3 Forbid() locking of this * list had some race conditions. * * * INPUTS * flags - Flags stating which types of nodes you want to lock. * * RESULT * dlist - Pointer to the head of the list. NOT a valid node. * ******* dos.library/UnLockDosList ************ * * NAME * UnLockDosList -- Unlocks the Dos List * * SYNOPSIS * UnLockDosList(flags) * D1 * * void UnLockDosList(ULONG) * * FUNCTION * Unlocks the access on the Dos Device List. * * INPUTS * flags - MUST be the same flags passed to (Attempt)LockDosList * ******* dos.library/AttemptLockDosList ************ * * NAME * AttemptLockDosList -- Attempt to lock the Dos Lists for use * * SYNOPSIS * dlist = AttemptLockDosList(flags) * D0 D1 * * struct DosList *AttemptLockDosList(ULONG) * * FUNCTION * Locks the dos device list in preparation to walk the list. * If the list is 'busy' then this routine will return NULL. * * INPUTS * flags - Flags stating which types of nodes you want to lock. * * RESULT * dlist - Pointer to the beginning of the list or NULL. * ******* dos.library/RemDosEntry ************ * * NAME * RemDosEntry -- Removes a Dos List entry from it's list * * SYNOPSIS * success = RemDosEntry(dlist) * D0 D1 * * BOOL RemDosEntry(struct DosList *) * * FUNCTION * This removes an entry from the Dos Device list. The memory associated * with the entry is NOT freed. NOTE: you must have locked the Dos List * with the appropriate flags before calling this routine. * * INPUTS * dlist - Device list entry to be removed. * * RESULT * success - Success/failure indicator * ******* dos.library/AddDosEntry ************ * * NAME * AddDosEntry -- Add a Dos List entry to the lists * * SYNOPSIS * success = AddDosEntry(dlist) * D0 D1 * * BOOL AddDosEntry(struct DosList *) * * FUNCTION * Adds a device, volume or assign to the dos devicelist. Can fail if it * conflicts with an existing entry (such as another assign to the same * name or another device of the same name). Volume nodes with different * dates and the same name CAN be added, or with names that conflict with * devices or assigns. Note: the dos list does NOT have to be locked to * call this. Do not access dlist after adding unless you have locked the * Dos Device list. * * INPUTS * dlist - Device list entry to be added. * * RESULT * success - Success/Failure indicator * ******* dos.library/FindDosEntry ************ * * NAME * FindDosEntry -- Finds a specific Dos List entry * * SYNOPSIS * newdlist = FindDosEntry(dlist,name,flags) * D0 D1 D2 D3 * * struct DosList *FindDosEntry(struct DosList *,UBYTE *,ULONG) * * FUNCTION * Locates an entry on the device list. Starts with the entry dlist. * NOTE: must be called with the device list locked, no references may be * made to dlist after unlocking. See also RemDosList, LockDosList. * * INPUTS * dlist - The device entry to start with. * name - Name of device entry (without ':') to locate. * flags - Search control flags. Use the flags you passed to * LockDosList, or a subset of them. LDF_READ/LDF_WRITE are * not required for this call. * * RESULT * newdlist - The device entry or NULL * ******* dos.library/NextDosEntry ************ * * NAME * NextDosEntry -- Get the next Dos List entry * * SYNOPSIS * newdlist = NextDosEntry(dlist,flags) * D0 D1 D2 * * struct DosList *NextDosEntry(struct DosList *,ULONG) * * FUNCTION * Find the next Dos List entry of the right type. You MUST have locked * the types you're looking for. Returns NULL if there are no more of * that type in the list. * * INPUTS * dlist - The current device entry. * flags - What type of entries to look for. (see FindDosEntry) * * RESULT * newdlist - The next device entry of the right type or NULL. * ******* dos.library/MakeDosEntry ************ * * NAME * MakeDosEntry -- Creates a DosList structure. * * SYNOPSIS * newdlist = MakeDosEntry(name, type) * D0 D1 D2 * * struct DosList *MakeDosEntry(UBYTE *, LONG) * * FUNCTION * Create a DosList structure, including allocating a name and correctly * null-terminating the BSTR. It also sets the dol_Type field, and sets * all other fields to 0. This routine should be * eliminated and replaced by a value passed to AllocDosObject! * * INPUTS * name - name for the device/volume/assign node. * type - type of node. * * RESULT * newdlist - The new device entry or NULL. * ******* dos.library/FreeDosEntry ************ * * NAME * FreeDosEntry -- Frees an entry created by MakeDosEntry * * SYNOPSIS * FreeDosEntry(dlist) * D1 * * void FreeDosEntry(struct DosList *) * * FUNCTION * Frees an entry created by MakeDosEntry. This routine should be * eliminated and replaced by a value passed to FreeDosObject! * * INPUTS * dlist - DosList to free. * * ******* dos.library/IsFileSystem ************ * * NAME * IsFileSystem -- returns whether a Dos handler is a filesystem or not. * * SYNOPSIS * result = IsFileSystem(name) * D0 D1 * * BOOL IsFileSystem(char *) * * FUNCTION * Returns whether the device is a filesystem or not. A filesystem * supports seperate files storing information. It may also support * sub-directories, but is not required to. * * INPUTS * name - Name of device in question, with trailing ':'. * * RESULT * result - Flag to indicate if device is a file system * ================= Handler Interface ================= ******* dos.library/Format ************ * * NAME * Format -- Causes a filesystem to initialize itself * * SYNOPSIS * rc = Format(filesystem) * D0 D1 * * BOOL Format(char *) * * FUNCTION * Interface for initializing new media on a device. For any sufficiently * large or even non-removable media this routine should provide an * interface to permit the user to back out of the action. This routine * will require some enhancement to the handler packet level interface in * order to implement. * * INPUTS * device - Name of device to be formatted. ':' must be supplied. * * RESULT * rc - Success/failure indicator. * * BUGS * not implemented yet * ******* dos.library/Relabel ************ * * NAME * Relabel -- Change the volume name of a volume * * SYNOPSIS * success = Relabel(volumename,name) * D0 D1 D2 * * BOOL Relabel(char *,char *) * * FUNCTION * Sends an ACTION_RENAME_DISK to the handler for the volume. Any * secondary result codes are returned through IOErr(). * * INPUTS * volumename - Full name of device to rename (with ':') * newname - New name to apply to device * * RESULT * success - Success/failure indicator * ******* dos.library/Inhibit ************ * * NAME * Inhibit -- Inhibits access to a filesystem * * SYNOPSIS * success = Inhibit(filesystem, flag) * D0 D1 D2 * * BOOL Inhibit(char *,LONG) * * FUNCTION * Sends an ACTION_INHIBIT packet to the indicated handler. This stops all * activity by the handler until uninhibited. When uninhibited, anything* * may have happened to the disk in the drive, or there may no longer be * one. * * INPUTS * filesystem - Name of device to inhibit (with ':') * flag - New status. DOSTRUE = inhibited, FALSE = uninhibited * * RESULT * success - Success/failure indicator * ******* dos.library/AddBuffers ************ * * NAME * AddBuffers -- Changes the number of buffers for a filesystem * * SYNOPSIS * success = AddBuffers(filesystem, number) * D0 D1 D2 * * BOOL AddBuffers(char *, LONG) * * FUNCTION * Adds buffers to a filesystem. If it succeeds, the number of current * buffers is returned in IoErr(). Note that "number" may be negative. * The amount of memory used per buffer, and any limits on the number of * buffers, are dependant on the filesystem in question. * If the call succeeds, the number of buffers in use on the filesystem * will be returned by IoErr(). * * INPUTS * filesystem - Name of device to add buffers to (with ':'). * number - Number of buffers to add. May be negative. * * RESULT * success - Success or failure of command. * ================== Date Time Routines ================== > void Delay(long); > long * DateStamp(long *); ******* dos.library/CompareDates ************ * * NAME * CompareDates -- Compares two datestamps * * SYNOPSIS * result = CompareDates(date1,date2) * D0 D1 D2 * * LONG CompareDates(struct DateStamp *,struct DateStamp *) * * FUNCTION * Compares two times for relative magnitide. <0 is returned if date1 is * later than date2, 0 if they are equal, or >0 if date2 is later than * date1. * * INPUTS * date1, date2 - DateStamps to compare * * RESULT * result - <0, 0, or >0 based on comparison of two date stamps * ******* dos.library/DateToStr ************ * * NAME * DateToStr -- Converts a DateStamp to a string * * SYNOPSIS * error = DateToStr( datetime ) * D0 D1 * * BOOL DateToStr(struct DateTime *) * * FUNCTION * StamptoStr converts an AmigaDOS DateStamp to a human * readable ASCII string as requested by your settings in the * DateTime structure. * * INPUTS * DateTime - a pointer to an initialized DateTime structure. * * The DateTime structure should be initialized as follows: * * dat_Stamp - a copy of the datestamp you wish to convert to * ascii. * * dat_Format - a format byte which specifies the format of the * dat_StrDate. This can be any of the following * (note: If value used is something other than those * below, the default of FORMAT_DOS is used): * * FORMAT_DOS: AmigaDOS format (dd-mmm-yy). * * FORMAT_INT: International format (yy-mmm-dd). * * FORMAT_USA: American format (mm-dd-yy). * * FORMAT_CDN: Canadian format (dd-mm-yy). * * dat_Flags - a flags byte. The only flag which affects this * function is: * * DTB_SUBST: If set, a string such as Today, * Monday, etc., will be used instead * of the dat_Format specification if * possible. * DTB_FUTURE: Ignored by this function. * * dat_StrDay - pointer to a buffer to receive the day of the * week string. (Monday, Tuesday, etc.). If null, this * string will not be generated. * * dat_StrDate - pointer to a buffer to receive the date * string, in the format requested by dat_Format, * subject to possible modifications by DTB_SUBST. If * null, this string will not be generated. * * dat_StrTime - pointer to a buffer to receive the time of day * string. If NULL, this will not be generated. * * RESULT * error - a non-zero return indicates that the DateStamp was * invalid, and could not be converted. Zero indicates * that everything went according to plan. * * SEE ALSO * StrtoDate(), libraries/datetime.h * ******* dos.library/StrToDate ************ * * NAME * StrToDate -- Converts a string to a DateStamp * * SYNOPSIS * error = StrToDate( datetime ) * D0 D1 * * BOOL StrToDate( struct DateTime * ) * * FUNCTION * Converts a human readable ASCII string into an AmigaDOS * DateStamp. * * INPUTS * DateTime - a pointer to an initialized DateTime structure. * * The DateTime structure should be initialized as follows: * * dat_Stamp - ignored on input. * * dat_Format - a format byte which specifies the format of the * dat_StrDat. This can be any of the following (note: * If value used is something other than those below, * the default of FORMAT_DOS is used): * * FORMAT_DOS: AmigaDOS format (dd-mmm-yy). * * FORMAT_INT: International format (yy-mmm-dd). * * FORMAT_USA: American format (mm-dd-yy). * * FORMAT_CDN: Canadian format (dd-mm-yy). * * dat_Flags - a flags byte. The only flag which affects this * function is: * * DTB_SUBST: ignored by this function * DTB_FUTURE: If set, indicates that strings such * as (stored in dat_StrDate) "Monday" * refer to "next" monday. Otherwise, * if clear, strings like "Monday" * refer to "last" monday. * * dat_StrDay - ignored bythis function. * * dat_StrDate - pointer to valid string representing the date. * This can be a "DTB_SUBST" style string such as * "Today" "Tomorrow" "Monday", or it may be a string * as specified by the dat_Format byte. This will be * converted to the ds_Days portion of the DateStamp. * If this pointer is NULL, DateStamp->ds_Days will not * be affected. * * dat_StrTime - Pointer to a buffer which contains the time in * the ASCII format hh:mm:ss. This will be converted * to the ds_Minutes and ds_Ticks portions of the * DateStamp. If this pointer is NULL, ds_Minutes and * ds_Ticks will be unchanged. * * RESULT * error - a non-zero return indicates that a conversion could * not be performed. A Zero return indicates that the * DateTime.dat_Stamp variable contains the converted * values. * * SEE ALSO * DateToStr(), libraries/datetime.h * ================ Image Management ================ > BPTR LoadSeg(char *); Returns value in both D0 and D1, so old versions of ovs.asm will work. Clears unused portions of Code and Data hunks (as well as BSS hunks). (This also applies to InternalLoadSeg and NewLoadSeg). > void UnLoadSeg(BPTR); ******* dos.library/NewLoadSeg ************ * * NAME * NewLoadSeg -- Improved version of LoadSeg for stacksizes * * SYNOPSIS * seglist = NewLoadSeg(file, tags) * D0 D1 D2 * * BPTR NewLoadSeg(UBYTE *, struct TagItem *) * * FUNCTION * Does a LoadSeg on a file, and takes additional actions based on the * tags supplied. * Clears unused portions of Code and Data hunks (as well as BSS hunks). * (This also applies to InternalLoadSeg and LoadSeg). * * INPUTS * file - Filename of file to load * tags - pointer to tagitem array * * RESULT * seglist - Seglist loaded, or NULL * ******* dos.library/InternalLoadSeg ************ * * NAME * InternalLoadSeg -- Low-level load routine * * SYNOPSIS * seglist = InternalLoadSeg(fh,table,functionarray,stack) * D0 D0 A0 A1 A2 * * BPTR InternalLoadSeg(BPTR,BPTR,LONG *,LONG *) * * FUNCTION * Loads from fh. Table is used when loading an overlay, otherwise should * be NULL. Functionarray is a pointer to an array of functions. Note * that the current Seek position after loading may be at any point after * the last hunk loaded. The filehandle will not be closed. If a * stacksize is encoded in the file, the size will be stuffed in the * LONG pointed to by stack. This LONG should be initialized to your * default value: LoadSeg will not change it if no stacksize is found. * Clears unused portions of Code and Data hunks (as well as BSS hunks). * (This also applies to LoadSeg and NewLoadSeg). * * If the file being loaded is an overlaid file, this will return * -(seglist). All other results will be positive. * * NOTE to overlay users: InternalLoadSeg does NOT return seglist in both * D0 and D1, as LoadSeg does. The current ovs.asm uses LoadSeg, and * assumes returns are in D1. We will support this for LoadSeg ONLY. * * INPUTS * fh - Filehandle to load from. * table - When loading an overlay, otherwise ignored. * functionarray - Array of function to be used for read, alloc, and free. * FuncTable[0] -> Actual = ReadFunc(readhandle,buffer,length),DOSBase * D0 D1 A0 D0 A6 * FuncTable[1] -> Memory = AllocFunc(size,flags), Execbase * D0 D0 D1 a6 * FuncTable[2] -> FreeFunc(memory,size), Execbase * A1 D0 a6 * stack - Pointer to storage (ULONG) for stacksize. * * RESULT * seglist - Seglist loaded or NULL. NOT returned in D1! * ******* dos.library/InternalUnLoadSeg ************ * * NAME * InternalUnLoadSeg -- Unloads a seglist loaded with InternalLoadSeg * * SYNOPSIS * InternalUnLoadSeg(seglist,FreeFunc) * D1 A1 * * void InternalUnLoadSeg(BPTR,void (*)(char *,ULONG)) * * FUNCTION * Unloads a seglist using freefunc to free segments. Freefunc is called * as for InternalLoadSeg. NOTE: will call Close() for overlaid seglists. * * INPUTS * FreeFunc - Function called to free memory * * RESULT * seglist - Seglist to be unloaded * AUTODOCS for AddSegment, FindSegment, RemSegment not written yet. FIX! =============== Command Support =============== ******* dos.library/CheckSignal ************ * * NAME * CheckSignal -- Checks for break signals * * SYNOPSIS * signals = CheckSignal(mask) * D0 D1 * * FUNCTION * This function checks to see if any signals specified in the mask have * been set and if so, returns them. Otherwise it returns FALSE. * All signals specified in mask will be cleared. * * INPUTS * mask - Signals to check for. * * RESULT * signals - Signals specified in mask that were set. * THIS AUTODOC IS WRONG, SEE DOS/RDARGS.H. WILL BE FIXED FOR BETA 2 + Count = rdargs( "line", len, args, "template" ) D0 A0 D0 A1 A2 Where: "line"/len represents the user command line to be parsed. args is a pointer to an array of 32 bit values defined as follows: args[0] points to a 256 byte scratch area for use by GADS as necessary. In the event of any error, it will contain the error message to be displayed to the user upon return. See below for error message formats. args[1..n] are use for return pointers to command results based on the template "template" is the standard AmigaDOS template with one extra extension that has become real obvious in all the commands: /N indicates that the parameter is to be parsed as a 32 bit integer. (i.e. call Stcd_l for it and verify the number) In addition, an enhanced version of GADS can also allow numbers to appear in the form 0x0000000 or even $0000000 for input of hex numbers. ERROR MESSAGES: One thing that is VERY clear with the existing commands is that there is not a consistent error message reporting nor even is there a consistant format for the error messages. Even when some of the errors are reported, it is often somewhat cryptic. In order to promote the highest level of consistancy both in AmigaDos commands and in any user programs that use them we propose the following messages be returned: * For a totally bogus command line: Arguments for <command> do not match "<template>" * For an invalid numeric argument: Invalid number <number> for <argname> * For a missing keyword (/K) argument: Missing operand for keyword <argname> Additional messages should also be documented. ******* dos.library/StrToLong ************ * * NAME * StrToLong -- string to long value (decimal) * * SYNOPSIS * characters = StrToLong(string,value) * D0 D1 D2 * * LONG StrToLong(UBYTE *,LONG *) * * FUNCTION * Converts decimal string into LONG value. Returns number of characters * converted. Skips over leading spaces & tabs (included in count). If no * decimal digits are found (after skipping leading spaces & tabs), * StrToLong returns -1 for characters converted, and puts 0 into value. * * INPUTS * string - Input string. * value - Pointer to long value. Set to 0 if no digits are converted. * * RESULT * result - Number of characters converted or -1. * ******* dos.library/MatchFirst ************ * * NAME * MatchFirst -- Finds file that matches pattern * * SYNOPSIS * rc = MatchFirst(pat, AnchorPath) * D0 D0 A0 * * BOOL MatchFirst(UBYTE *, struct AnchorPath *) * * FUNCTION * Locates the first file or directory that matches a given pattern. * This routine should support the concept of an ALL bit as well as * handle ^c signals gracefully. * * INPUTS * pat - Pattern to search for * AnchorPath - Place holder for search. MUST be longword aligned! * * RESULT * rc - Success/failure indicator * ******* dos.library/MatchNext ************ * * NAME * MatchNext - Finds the next file or directory that matches pattern * * SYNOPSIS * rc = MatchNext(AnchorPath) * D0 A0 * * BOOL MatchNext(struct AnchorPath *) * * FUNCTION * Locates the next file or directory that matches a given pattern. * This routine should support the concept of an ALL bit as well as * handle ^c signals gracefully. Called after calling MatchFirst(). * * INPUTS * AnchorPath - Place holder for search. MUST be longword aligned! * * RESULT * rc - Success/failure indicator * ******* dos.library/MatchEnd ************ * * NAME * MatchEnd -- Free storage allocated for MatchFirst/MatchNext * * SYNOPSIS * MatchEnd(AnchorPath) * A0 * * void MatchEnd(struct AnchorPath *) * * FUNCTION * Return all storage associated with a given search. * * INPUTS * AnchorPath - Anchor used for MatchFirst/MatchNext * MUST be longword aligned! * ******* dos.library/MatchPattern ************ * * NAME * MatchPattern -- Checks for a pattern match with a string * * SYNOPSIS * result = MatchPattern(pat, str) * D0 A0 A1 * * BOOL MatchPattern(UBYTE *, UBYTE *) * * FUNCTION * Checks for a pattern match with a string. * * INPUTS * pat - Special pattern string to match as returned by ParsePattern * str - String to match against given pattern * * RESULT * result - Indication of match for given pattern. * ********************************************************************** * * NAME * ParsePattern -- Creat a tokenized string for MatchPattern * * SYNOPSIS * IsWild = ParsePattern(Source,Dest,DestLength) * d0 D1 D2 D3 * * FUNCTION * * INPUTS * UBYTE *source - unparsed wildcard string to search for. * UBYTE *dest - output string, gets tokenized version of input. * * RESULT * BOOL IsWild - whether there were any wildcards in the string * * ====================== Notification ====================== ******* dos.library/StartNotify ************ * * NAME * StartNotify -- Starts notification on a file or directory * * SYNOPSIS * rc = StartNotify(notifystructure) * D0 D1 * * BOOL StartNotify(struct NotifyRequest *) * * FUNCTION * Posts a notification request. Do not modify the notify structure while * it is active. You will be notified when the file or directory changes. * For files, you will be notified after the file is closed. Not all * filesystems will support this: applications should NOT require it. In * particular, most network filesystems won't support it. * * INPUTS * notifystructure - A filled in NotifyRequest structure * * RESULT * rc - Success/failure of request * ******* dos.library/EndNotify ************ * * NAME * EndNotify -- Ends a notification request * * SYNOPSIS * EndNotify(notifystructure) * D1 * * void EndNotify(struct NotifyRequest *) * * FUNCTION * Removes a notification request. Safe to call even if StartNotify * failed. * * INPUTS * notifystructure - a structure passed to StartNotify * ============================== Variable functions ============================== ******* dos.library/DeleteVar ************ * * NAME * DeleteVar -- Deletes a local or environment variable * * SYNOPSIS * rc = DeleteVar( name, flags ) * D0 D1 D2 * * BOOL DeleteVar(UBYTE *, ULONG ) * * FUNCTION * Deletes a local or environment variable. * * INPUTS * name - pointer to an variable name. Note variable names follow * filesystem syntax and semantics. * flags - combination of type of var to delete (low 8 bits), and * flags to control the behavior of this routine. Currently * defined flags include: * * GVF_LOCAL_ONLY - delete a local (to your process) variable. * GVF_GLOBAL_ONLY - delete a global environment variable. * * The default is to delete a local variable if found, otherwise * a global environment variable if found (only for LV_VAR). * * RESULT * rc - If TRUE, the variable was sucessfully deleted, FALSE * indicates failure. * * BUGS * LV_VAR is the only type that can be global * * SEE ALSO * GetVar(), SetVar(), libraries/var.h * ******* dos.library/FindVar ************ * * NAME * FindVar -- Finds a local variable * * SYNOPSIS * var = DeleteVar( name, type ) * D0 D1 D2 * * struct LocalVar * FindVar(UBYTE *, ULONG ) * * FUNCTION * Finds a local variable. * * INPUTS * name - pointer to an variable name. Note variable names follow * filesystem syntax and semantics. * * type - type of variable to be found (see libraries/var.h) * * RESULT * * var - pointer to a LocalVar structure or NULL * * SEE ALSO * GetVar(), SetVar(), DeleteVar(), libraries/var.h * ******* dos.library/SetVar ************ * * NAME * SetVar -- Sets a local or environment variable * * SYNOPSIS * rc = SetVar( name, buffer, size, flags ) * D0 D1 D2 D3 D4 * * BOOL SetVar(UBYTE *, UBYTE *, LONG, ULONG ) * * FUNCTION * Sets a local or environment variable. It is advised to only use * ASCII strings inside variables, but not required. * * INPUTS * name - pointer to an variable name. Note variable names follow * filesystem syntax and semantics. * buffer - a user allocated area which contains a string that is the * value to be associated with this variable. * size - length of the buffer region in bytes. -1 means buffer contains * a null-terminated string. * flags - combination of type of var to set (low 8 bits), and * flags to control the behavior of this routine. Currently * defined flags include: * * GVF_LOCAL_ONLY - set a local (to your process) variable. * GVF_GLOBAL_ONLY - set a global environment variable. * * The default is to set a local environment variable. * * RESULT * * rc - If TRUE, the variable was sucessfully set, FALSE * indicates failure. * * BUGS * LV_VAR is the only type that can be global * * SEE ALSO * GetVar(), DeleteVar(), libraries/var.h * ******* dos.library/GetVar ************ * * NAME * GetVar -- Returns the value of a local or global variable * * SYNOPSIS * len = GetVar( name, buffer, size, flags ) * D0 D1 D2 D3 D4 * * LONG GetVar( UBYTE *, UBYTE *, LONG, ULONG ) * * FUNCTION * Gets the value of a local or environment variable. It is advised to * only use ASCII strings inside variables, but not required. * * INPUTS * name - pointer to a variable name. * buffer - a user allocated area which will be used to store * the value associated with the variable. * size - length of the buffer region in bytes. * flags - combination of type of var to get value of (low 8 bits), and * flags to control the behavior of this routine. Currently * defined flags include: * * GVF_GLOBAL_ONLY - tries to get a global env variable. * GVF_LOCAL_ONLY - tries to get a local variable. * * The default is to try to get a local variable first, then * to try to get a global environment variable. * * RESULT * len - Size of environment variable. -1 indicates that the * variable was NOT DEFINED. If the value would overflow * the user buffer, the buffer is truncated. The buffer * returned is null-terminated. The actual full length of the * variable is returned. * * (non-truncated return values range from 0 ..size-1 ). * It is advised to check for and ignore a trailing newline * character ('\n', 0x0A) in the returned buffer for textual * variables. * * BUGS * LV_VAR is the only type that can be global * * SEE ALSO * SetVar(), DeleteVar(), libraries/var.h * ******* dos.library/FilePart ************ * * NAME * FilePart -- Returns the last component of a path * * SYNOPSIS * fileptr = FilePart( path ) * D0 D1 * * UBYTE *FilePart( UBYTE * ) * * FUNCTION * This function returns a pointer to the last component of a string path * specification, which will normally be the file name. If there is only * one component, it returns a pointer to the beginning of the string. * * INPUTS * path - pointer to an path string. May be relative to the current * directory or the current disk. * * RESULT * fileptr - pointer to the last component of the path. * * EXAMPLE * FilePart("xxx:yyy/zzz/qqq") would return a pointer to the first 'q'. * FilePart("xxx:yyy") would return a pointer to the first 'y'). * * SEE ALSO * PathName() * ******* dos.library/PathPart ************ * * NAME * PathPart -- Returns a pointer to the end of the next-to-last * component of a path. * * SYNOPSIS * fileptr = PathPart( path ) * D0 D1 * * UBYTE *PathPart( UBYTE * ) * * FUNCTION * This function returns a pointer to the character after the next-to-last * component of a path specification, which will normally be the directory * name. If there is only one component, it returns a pointer to the * beginning of the string. The only real difference between this and * FilePart() is the handling of '/'. * * INPUTS * path - pointer to an path string. May be relative to the current * directory or the current disk. * * RESULT * fileptr - pointer to the end of the next-to-last component of the path. * * EXAMPLE * PathPart("xxx:yyy/zzz/qqq") would return a pointer to the last '/'. * PathPart("xxx:yyy") would return a pointer to the first 'y'). * * SEE ALSO * FilePart() * ******* dos.library/AddPart ************ * * NAME * AddPart -- Appends a file/dir to the end of a path * * SYNOPSIS * rc = AddPart( dirname, filename, size ) * D0 D1 D2 D3 * * BOOL AddPart( UBYTE *, UBYTE *, ULONG ) * * FUNCTION * This function adds a file, directory, or subpath name to a directory * path name taking into account any required separator characters. * * INPUTS * dirname - the path to add a file/directory name to. * filename - the filename or directory name to add. May be a relative * pathname from the current directory (example: foo/bar). * Can deal with leading '/'(s), indicating one directory up * per '/'. * size - size in bytes of the space allocated for dirname. Must * not be 0. * * RESULT * * rc - DOSTRUE for ok, FALSE if the buffer would have overflowed. If * an overflow would have occured, dirname will not be changed. * * BUGS * Doesn't check if a subpath is legal (i.e. doesn't check for ':'s). * * SEE ALSO * Filepart(), PathPart() *